N ECat文档中心

ECat Harmony SDK使用文档#

功能说明：基于鸿蒙API 12，支持cpp crash、js crash、Freeze等异常捕获，同时支持Unity团结引擎。

一、接入步骤#

1.1 SDK文件说明#

  • ECat.har：鸿蒙SDK静态库

1.2 DevEco Studio SDK集成#

  1. 将SDK文件复制到entry模块的libs目录下

  2. 在entry的oh-package.json5中增加以下配置：

"dependencies": {
    "ECat": "file:libs/ECat.har",
}

1.3 初始化SDK#

//导入类
import { ECat, ECatInitConfig } from 'ECat'

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
        hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');

        //初始化配置
        let config = new ECatInitConfig();
        config.enableDebugMode = true; //是否启用调试模式（默认：false，正式发布的版本请设置为fasle）
        config.appVersion = "v1"; //应用版本，若为空则自动获取BundleInfo.versionName
        config.appChannel = "Channel"; //渠道
        config.userId = "uid1000"; //用户id
        
        //初始化
        ECat.init(this.context, "平台分配的AppId", config);
  }
}

1.3.1 网络权限设置#

特别注意：为合规性要求，ECat初始化后默认不会上传数据！调用权限设置接口后才会上传数据

  • 如果INTERNET权限需要用户授权，则在授权后调用（仅调用一次，下次打开应用后无需调用）
  • 如果不需要用户授权，则在初始化后直接调用：
ECat.setPermission("INTERNET", true);

1.4 接入测试#

在初始化后，运行app，手动制造一个崩溃并重启应用

ECat.testNativeCrash();

在配置类中设置enableDebugMode = true后，重启应用后可在Hilog中查看崩溃日志。

也可在ECat平台->控制台->异常列表中查看数据。

1.5 符号文件上传#

有关符号文件的说明见《符号文件上传工具使用文档》

二、API说明#

2.1 ECatInitConfig类#

用于初始化时的配置

export class ECatInitConfig {
  appVersion = "";
  appChannel = "";
  userId = "";
  enableDebugMode = false;
}

2.2 ECat类#

该类提供ECat API接口

export class ECat {
	/**
     * 初始化ECat
     * @param context   上下文(必须是应用ability的Context)
     * @param appId     注册时申请的APPID
     * @param config 用户自定义的配置
     */
    static init(context: Context, appId: string, config: ECatInitConfig);

    /**
     * 测试 NDK 层崩溃
     */
    static testNativeCrash();

	/**
     * 上报捕获的ts Error
     */
	static reportError(e:Error);

    /**
     * 上传自定义异常
     */
    static reportExceptionWithType(type:number, name:string, message:string, stacktrace:string);

    /**
     * 自定义标签，用于标明App的某个“场景”。以最后设置的标签为准，标签id需大于0
     */
    static setTag(tag:number);

    /**
     * 自定义Map参数，在发生异常时会随着异常信息一起上报并在页面展示。
     */
    static addKeyValue(key:string, value:string);

    /**
     * 删除Key
     */
    static removeKeyValue(key:string);
    /**
     * 设置当前用户 ID
     */
    static setUserId(userId:string);
        
    /**
     * 设置app版本
     */
    static setAppVersion(ver:string);
    
    /**
     * 设置应用处于前后台(在非主线程初始化时，在监听回调中调用)
     */
    static setAppForeground(isForeground:boolean);
    
    /**
     * 在用户同意权限申请后，设置对应权限状态。如不需要用户同意，可在初始化Crashlytics后设置
     * @param permission 目前支持"INTERNET"
     * @param enable 是否获取到permission
     */
    static setPermission(permission:string, enable:boolean);
    
    /**
     * 获取上次退出信息
     */
    static getLastExitInfo():string;
}

三、FAQ#

  1. 崩溃上传的时机是什么时候？

    崩溃和Freeze捕获都是基于hiAppEvent，此api只能在应用崩溃后，下一次重启时触发。因此崩溃和Freeze都是在发生事件后，下一次启动时上传

  2. 能否在子线程中调用异常上报接口？

    可以，前提条件是必须在主线程中完成初始化